openapi: 3.0.0
info:
  version: 1.0.0
  title: GeoServer Styles
  description: A style describes how a resource is symbolized or rendered by the Web Map Service.

servers:
  - url: http://localhost:8080/geoserver/rest
  
security:
  - basicAuth: []

tags:
  - name: styles
    description: Styles API

paths:
  /styles:
    get:
      operationId: getStyles
      tags:
        - styles
      summary: Get a list of styles
      description: Displays a list of all styles on the server.
      responses:
        "200":
          $ref: '#/components/responses/StyleList'
    post:
      operationId: createStyle
      tags:
        - styles
      summary: Add a new style
      description: >
        Adds a new style entry to the server.
        Using POST with the `application/xml` or `application/json` content only adds the style info to the catalog and does not upload style content. PUT to `/styles/{style}` to upload the style in this case.
        Use POST with a style file (`application/vnd.ogc.sld+xml` or `application/vnd.ogc.sld+xml` for SLD; additional style types are added by extensions) to generate a style info and upload the style all at once. Then seperately PUT the style info at `/styles/{style}` to make any desired changes to the generated catalog entry.
        You can also use POST with a ZIP file to upload a SLD 1.0 (`application/vnd.ogc.sld+xml`) file and any associated icon files, and then separately PUT the style info at /styles/{style}. POST with a ZIP file does not support any other style types.
      parameters:
        - name: name
          in: query
          description: The name of the style. Used only when POSTing a style file or ZIP
            bundle, to determine the name of the style in the catalog. Generated
            from the filename if not provided.
          required: false
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/StyleInfoPost"
      responses:
        "201":
          $ref: "#/components/responses/CreateStyleResponse"

  /styles/{style}:
    parameters:
      - name: style
        in: path
        required: true
        description: Name of the style to retrieve.
        schema:
          type: string
    get:
      operationId: getStyle
      tags:
        - styles
      summary: Retrieve a style
      description: >
        Retrieves a single style. Used to both request the style info and the style defintion body, depending on the media type requested. The media
        type can be specified either by using the "Accept:" header or by appending an extension to the endpoint. For example, a style info can be
        requested in XML format using "/styles/{style}.xml" or "Accept: application/xml". (Also available: "{style}.json", 
        "Accept: application/json" "{style}.html", and "Accept: text/html").

        The style definition body can be requested by either appending the file extension of the style file (e.g., "{style}.sld" or "{style}.css") or by specifying the correct media type for the style definition in the "Accept" header. Below are common style formats and the corresponding media types that can be used in the Accept header to request the style definition body.

        - application/vnd.ogc.sld+xml for SLD 1.0.0 SLDs
        - application/vnd.ogc.se+xml for SLD 1.1.0 SLDs
        - application/vnd.geoserver.geocss+css for css styles
        - application/vnd.geoserver.ysld+yaml for ysld styles
        - application/vnd.geoserver.mbstyle+json for mb styles
      responses:
        "200":
          $ref: "#/components/responses/StyleInfoResponse"
    put:
      operationId: uploadStyle
      tags:
        - styles
      summary: Modify a single style
      description: Modifies a single style.
        Use the "Accept:" header to specify format or append an extension to the endpoint (example `/styles/{style}.xml` for XML).
        Using PUT with the `application/xml` or `application/json` content modifies the style info in the catalog and does not alter the style content.
        Using PUT with any other format will modify the content of the style. You can also use PUT with a ZIP file to upload a SLD 1.0 (`application/vnd.ogc.sld+xml`) file and any associated icon files
      parameters:
        - name: raw
          in: query
          description: When set to "true", will forgo parsing and encoding of the uploaded
            style content, and instead the style will be streamed directly to
            the GeoServer configuration. Use this setting if the content and
            formatting of the style is to be preserved exactly. May result in an
            invalid and unusable style if the payload is malformed. Allowable
            values are "true" or "false" (default). Only used when uploading a
            style file.
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: "#/components/requestBodies/StyleBody"
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
    delete:
      operationId: deleteStyle
      tags:
        - styles
      summary: Delete style
      description: Deletes a style.
      parameters:
        - name: purge
          in: query
          required: false
          description: Specifies whether the underlying file containing the style should be
            deleted on disk.
          schema:
            type: boolean
            default: false
        - name: recurse
          in: query
          required: false
          description: Removes references to the specified style in existing layers.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized

  /workspaces/{workspace}/styles:
    parameters:
      - name: workspace
        in: path
        required: true
        description: Name of workspace
        schema:
          type: string
    get:
      operationId: getStylesByWorkspace
      tags:
        - styles
      summary: Get a list of styles in a given workspace
      description: Displays a list of all styles in a given workspace. Use the "Accept:"
        header to specify format or append an extension to the endpoint (example "/workspaces/{workspace}/styles.xml" for XML).
      responses:
        "200":
          $ref: '#/components/responses/StyleList'
    post:
      operationId: createStyleByWorkspace
      tags:
        - styles
      summary: Add a new style to a given workspace
      description: Adds a new style entry to the server.
        Using POST with the `application/xml` or `application/json` content only adds the style info to the catalog and does not upload style content. PUT to `/workspaces/{workspace}/styles/{style}` to upload the style in this case.
        Use POST with a style file (`application/vnd.ogc.sld+xml` or `application/vnd.ogc.sld+xml` for SLD; additional style types are added by extensions) to generate a style info and upload the style all at once. Then seperately PUT the style info at `/workspaces/{workspace}/styles/{style}` to make any desired changes to the generated catalog entry.
        You can also use POST with a ZIP file to upload a SLD 1.0 (`application/vnd.ogc.sld+xml`) file and any associated icon files, and then separately PUT the style info at /workspaces/{workspace}/styles/{style}. POST with a ZIP file does not support any other style types.
      parameters:
        - name: name
          in: query
          description: The name of the style. Used only when POSTing a style file or ZIP
            bundle, to determine the name of the style in the catalog. Generated from the filename if not provided.
          required: false
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/StyleInfoPost"
      responses:
        "201":
          $ref: "#/components/responses/CreateStyleResponse"



  /workspaces/{workspace}/styles/{style}:
    parameters:
      - name: workspace
        in: path
        required: true
        description: Name of the workspace for style definitions
        schema:
          type: string
      - name: style
        in: path
        required: true
        description: Name of the style to retrieve.
        schema:
          type: string
    get:
      operationId: getStyleByWorkspace
      tags:
        - styles
      summary: Retrieve a style from a given workspace
      description: >
        Retrieves a single style. Used to both request the style info and the
        style defintion body, depending on the media type requested. The media
        type can be specified either by using the "Accept:" header or by
        appending an extension to the endpoint. For example, a style info can be
        requested in XML format using "/styles/{style}.xml" or "Accept:
        application/xml". (Also available: "{style}.json", "Accept:
        application/json" "{style}.html", and "Accept: text/html").

        The style definition body can be requested by either appending the file extension of the style file (e.g., "{style}.sld" or "{style}.css") or by specifying the correct media type for the style definition in the "Accept" header. Below are common style formats and the corresponding media types that can be used in the Accept header to request the style definition body.
        - application/vnd.ogc.sld+xml for SLD 1.0.0 SLDs
        - application/vnd.ogc.se+xml for SLD 1.1.0 SLDs
        - application/vnd.geoserver.geocss+css for css styles
        - application/vnd.geoserver.ysld+yaml for ysld styles
        - application/vnd.geoserver.mbstyle+json for mb styles
      parameters:
        - in: query
          name: quietOnNotFound
          required: false
          schema:
             type: boolean
             default: true
      responses:
        "200":
          $ref: "#/components/responses/StyleInfoResponse"
    put:
      operationId: uploadStyleByWorkspace
      tags:
        - styles
      summary: Modify a single style in a given workspace
      description: >
        Modifies a single style in a given workspace.
        Use the "Accept:" header to specify format or append an extension to the endpoint (example `/workspaces/{workspace}/styles/{style}.xml` for XML).
        Using PUT with the `application/xml` or `application/json` content modifies the style info in the catalog and does not alter the style content.
        Using PUT with any other format will modify the content of the style. You can also use PUT with a ZIP file to upload a SLD 1.0 (`application/vnd.ogc.sld+xml`) file and any associated icon files
      parameters:
        - name: raw
          in: query
          description: When set to "true", will forgo parsing and encoding of the uploaded
            style content, and instead the style will be streamed directly to
            the GeoServer configuration. Use this setting if the content and
            formatting of the style is to be preserved exactly. May result in an
            invalid and unusable style if the payload is malformed. Allowable
            values are "true" or "false" (default). Only used when uploading a
            style file.
          required: false
          schema:
            type: boolean
      requestBody:
        $ref: "#/components/requestBodies/StyleBody"
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
    delete:
      operationId: deleteStyleByWorkspace
      tags:
        - styles
      summary: Delete style in a given workspace
      description: Deletes a style in a given workspace.
      parameters:
        - name: purge
          in: query
          required: false
          description: Specifies whether the underlying file containing the style should be
            deleted on disk.
          schema:
            type: boolean
            default: false
        - name: recurse
          in: query
          required: false
          description: Removes references to the specified style in existing layers.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized

  /layers/{layer}/styles:
    parameters:
      - name: layer
        in: path
        required: true
        description: Name of the layer to manage styles for
        schema:
          type: string
    get:
      operationId: getStylesByLayer
      tags:
        - styles
      summary: Get a list of layer alternate styles
      description: Displays a list of all alternate styles for a given layer. Use the
        "Accept:" header to specify format or append an extension to the endpoint (example "/layers/{layer}/styles.xml" for XML).
      responses:
        "200":
          description: OK
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/StyleList"
            application/json:
              schema:
                $ref: "#/components/schemas/StyleList"
              examples:
                response:
                  value: >
                    {
                      "styles": {
                        "style": [
                          {
                            "name": "pophatch",
                            "href": "http://localhost:8080/geoserver/rest/layers/topp:states/styles/pophatch.json"
                          },
                          {
                            "name": "polygon",
                            "href": "http://localhost:8080/geoserver/rest/layers/topp:states/styles/polygon.json"
                          }
                        ]
                      }
                    }
            text/html:
              schema:
                $ref: "#/components/schemas/StyleList"
    post:
      operationId: addStyleToLayer
      tags:
        - styles
      summary: Add a new style
      description: Adds a new style entry to the layer. The style named in styleBody must
        alread exist, and will not be altered by this request.
      parameters:
        - name: default
          in: query
          description: Whether to make this the default style for the layer.
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        content:
          application/xml:
            schema:
              $ref: "#/components/schemas/StyleInfoPost"
          application/json:
            schema:
              $ref: "#/components/schemas/StyleInfoPost"
        description: Style body information naming an existing style to add to the layer
        required: true
      responses:
        "201":
          description: Created

components:
  securitySchemes:
    basicAuth:     # <-- arbitrary name for the security scheme
      type: http
      scheme: basic

  requestBodies:
    StyleInfoPost:
      required: true
      description: The StyleInfo body of a request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StyleInfoWrapper"
        application/zip:
          schema:
            type: string
            format: binary

    StyleBody:
      required: true
      description: The style body of a request.
      content:
        application/vnd.geoserver.mbstyle+json:
          schema:
            type: string
            format: binary
        application/vnd.ogc.sld+xml:
          schema:
            type: string
            format: binary
        application/vnd.ogc.se+xml:
          schema:
            type: string
            format: binary
      
  responses:
    CreateStyleResponse:
      description: Created, returns the name of the style in plain text
      content:
        text/plain:
          schema:
            type: string
    
    StyleList:
      description: List of style references
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StyleListWrapper"
    StyleInfoResponse:
      description: List of style references
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StyleInfoWrapper"
        application/xml:
          schema:
            type: string
        application/vnd.ogc.sld+xml:
          schema:
            type: string
        application/vnd.ogc.se+xml:
          schema:
            type: string
        text/html:
          schema:
            type: string

  schemas:
    StyleInfoPost:
      title: style
      type: object
      properties:
        name:
          type: string
          description: Name of style
          example: roads_style
        filename:
          type: string
          description: Name of filename containing SLD code
          example: roads.sld
    StyleListWrapper:
      type: object
      properties:
        styles:
          $ref: "#/components/schemas/StyleList"
      example:
        styles:
         style:
           - href: http://localhost:8080/geoserver/rest/styles/burg.json
             name: burg
           - href: http://localhost:8080/geoserver/rest/styles/capitals.json
             name: capitals
    StyleInfoWrapper:
      type: object
      properties:
        style:
          $ref: "catalog.yaml#/components/schemas/StyleInfo"
        
    StyleList:
      type: object
      properties:
        style:
          $ref: "catalogresponses.yaml#/components/schemas/NamedLinks"
